home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / MPW Additions / ModPEF Notes < prev    next >
Text File  |  1996-05-07  |  13KB  |  373 lines
  1. ModPEF Notes for "Mac OS 8 Resources"
  2. ModPEF 1.0d5 Released for WWDC, May 1996
  3. Copyright:    © 1994-1996 by Apple Computer, Inc.
  4.                  All rights reserved.
  5.                 
  6. #########################################################################
  7. **  NOTE:  This is an engineering build and has not been fully tested ***
  8. #########################################################################
  9.  
  10.                                          ModPEF
  11.                               A utility for PEF fragments
  12.  
  13.  
  14. ============
  15. What it does
  16. ============
  17.  
  18. ModPEF copies fragments from an existing PEF file to a new PEF file, optionally
  19. editing fragment attributes as they are copied.  ModPEF does not touch the resource 
  20. fork except for reading/writing the 'cfrg' resource and copying 'rseg' and 'CODE' 
  21. resources for CFM-68K PEF containers.
  22.  
  23.  
  24.  
  25. ====================
  26. Command line options
  27. ====================
  28.  
  29. ModPEF [option...] file... >= progress
  30.    -@addexports <fragspec> = <filename>       # Add exported symbols to fragment
  31.                                               # <filename> contains names of symbols
  32.    -@alias <fragspec> = <filename>            # Allow aliases to exported symbol names
  33.    -c creator                                 # Set file creator
  34.    -delete <fragspec> , ...                     # Delete fragments from file
  35.    -deleteexports <fragspec> = <aName> , ...    # Delete exported symbols from fragment
  36.    -@deleteexports <fragspec> = <filename>    # Delete exported symbols from fragment 
  37.                                               # <filename> contains names of symbols
  38.    -describe on | off                         # Describe which fragments are affected
  39.                                               # (Default is on)
  40.    -extract <fragspec> , ...                    # Extract fragments from file
  41.    -[no]initbefore <fragspec> = <aName> , ...   # Modify fragment's "initbefore" settings
  42.    -level <fragspec> = <aLevel>               # Change how fragment is used
  43.    -list                                      # List contents of file
  44.    -mergecode on | off                        # Make code sections adjacent (default is off)
  45.    -o <filename>                              # Set output file name
  46.    -p                                         # Write progress information to diagnostics
  47.    -renamefrag <fragspec> = <aName>           # Rename a fragment
  48.    -@renamesymbols <fragspec> = <filename>    # Rename fragment's imported/exported symbols
  49.    -share <fragspec> = context | global | protected | <aNumber>
  50.                                               # Change fragment's data section sharing attribute
  51.    -stacksize <fragspec> = <aNumber>          # Set fragment's stack size
  52.    -t type                                    # Set file type
  53.    -usage <fragspec> = library | application | dropin | <aNumber>
  54.                                               # Change fragment's usage type
  55.    -v                                         # Use verbose progress (implies -p)
  56.    -vercur <fragspec> = <aNumber>             # Change fragment's current version
  57.    -verdef <fragspec> = <aNumber>             # Change fragment's definition version
  58.    -verimp <fragspec> = <aNumber>             # Change fragment's implementation version
  59.    -[no]weak <fragspec> = <aName> , ...         # Modify fragment's weak imports
  60.    -[no]weaklib <fragspec> = <aName> , ...      # Modify fragment's weak libraries
  61.  
  62.  
  63.     <fragspec>        ::= <aName>[ '(' <fraginfo> , ... ')' ]
  64.     <fraginfo>      ::= <anArch>                   # Which architecture
  65.                         arch = <anArch>            #
  66.                         arch = <aNumber>           #
  67.                         <aLevel>                   # Base library or update library
  68.                         level = <aLevel>           #
  69.                         level = <aNumber>          # 
  70.                         vercur = <aNumber>         # Current version
  71.                         verdef = <aNumber>         # Definition version
  72.  
  73.     <aName>            ::=    characters other than "," "(", ")" and "="
  74.                         "*"                        # Wild card: match any fragment name
  75.     <aNumber>        ::=    <decimal> | $<hex> | 0x<hex>
  76.     <anArch>        ::=    pwpc | m68k
  77.     <aLevel>        ::=    base | update
  78.  
  79.  
  80.  
  81. ==============
  82. Some Scenarios
  83. ==============
  84.  
  85. To extract fragments
  86. --------------------
  87.  
  88.         ModPEF    -extract 'InterfaceLib(vercur=12)'    [partial]
  89.                 -extract 'CPlusLib'                    [partial]
  90.                 -extract 'QuickTimeLib(verdef=3)'    [partial]
  91.                 oldLibrary                            [partial]
  92.                 -o fragLibrary
  93.  
  94.     All fragments named 'CPlusLib" are extracted, all 'InterfaceLib' fragments 
  95.     whose current version number is 12 and all 'QuickTimeLib' fragments whose 
  96.     definition version number is 3 are copied from "oldLibrary" and written 
  97.     to "fragLibrary".  "oldLibrary" is not modified.
  98.  
  99.  
  100.  
  101. To delete fragments
  102. --------------------
  103.  
  104.         ModPEF    -o newLibrary                        [partial]
  105.                 oldLibrary                            [partial]
  106.                 -delete  'InterfaceLib(vercur=12)'    [partial]
  107.                 -delete  'CPlusLib(pwpc)'            [partial]
  108.                 -delete  'QuickTimeLib(verdef=3)'
  109.  
  110.     The specified fragments are deleted when "oldLibrary" is copied to "newLibrary".
  111.     "oldLibrary" is not modified.
  112.  
  113.  
  114.  
  115. To change the stacksize for an application
  116. ------------------------------------------
  117.  
  118.         ModPEF    myNiftyApp                            [partial]
  119.                 -stacksize myNiftyApp=$20000        [partial]
  120.                 -o myNiftyApp.new
  121.  
  122.     The stacksize required by "myNiftyApp" is changed to $20000 bytes.  The 
  123.     changed file is written to "myNiftyApp.new".  "myNiftyApp" is not 
  124.     modified.
  125.  
  126.  
  127.  
  128. ======================
  129. Description of options
  130. ======================
  131.  
  132.  
  133. Listing fragments
  134. -----------------
  135.  
  136.     ModPEF <file> -list
  137.  
  138.         An input file is required.
  139.  
  140.         Writes the names of the fragments specified in the 'cfrg'(0) resource of
  141.         the file.
  142.  
  143.  
  144. Deleting fragments
  145. ------------------
  146.  
  147.     ModPEF <old> -o <new> -delete <fragspec>
  148.  
  149.         An input file and output file are required.
  150.  
  151.         Each <fragspec> must be preceded by the "-delete" option. 
  152.  
  153.         All fragments from <old> are copied to <new> except for those named by 
  154.         the <fragspecs>.
  155.  
  156.  
  157. Extracting fragments
  158. --------------------
  159.  
  160.     ModPEF <old> -o <new> -extract <fragspec>
  161.  
  162.         An input file and output file are required.
  163.  
  164.         Each <fragspec> must be preceded by the "-extract" option. 
  165.  
  166.         All fragments from <old> matching the <fragspec>s are copied to <new>.  
  167.  
  168.  
  169. Changing fragment attributes
  170. ----------------------------
  171.  
  172.     ModPEF    <old> -o <new>
  173.         [-delete <fragspec>]
  174.         [-extract <fragspec>]
  175.         -level <fragspec> = <aLevel>
  176.         -[no]initbefore <fragspec> = <aName> , ...
  177.         [-mergecode on | off]
  178.         -rename <fragspec> = <aName>
  179.         -share <fragspec> = context | global | protected | <aNumber>
  180.         -stacksize <fragspec> = <aNumber>
  181.         -usage <fragspec> = library | application | dropin
  182.         -vercur <fragspec> = <aNumber>
  183.         -verdef <fragspec> = <aNumber>
  184.         -verimp <fragspec> = <aNumber>
  185.         -[no]weak <fragspec> = <aName> , ...
  186.         -[no]weaklib <fragspec> = <aName> , ...
  187.  
  188.         An input file and output file are required.
  189.  
  190.         The -delete and -extract are optional.  If -delete is present, all fragments
  191.         except those marked for deletion are copied and/or modified.  If -extract is
  192.         present, only those fragments marked for extraction are copied and/or modified.
  193.         Combining both -delete and -extract is incorrect.
  194.  
  195.         Fragments from <old> are copied to <new>.  Those fragments matching the 
  196.         <fragspec>s are modified according to the <options> associated with the 
  197.         <fragspec>.  If a single fragment is matched by several options, the 
  198.         changes are done in order of command line appearance.  Renaming or 
  199.         changing version numbers does not affect matching: the matching is done 
  200.         prior to any renaming/reversioning.
  201.  
  202.  
  203. To add export symbols to a fragment
  204. -----------------------------------
  205.  
  206.     ModPEF <old> -o <new> -@addexports <fragspec>=<filename>
  207.  
  208.     The symbols contained in the file <filename> are added to the exported 
  209.     symbols section of the <fragspec> fragment.  The new file is written 
  210.     to <new>.
  211.  
  212.     Format of the lines in the -@addexports file is 
  213.  
  214.             <name> <section>[:]<offset> [<class>]
  215.  
  216.     <name> is anything without embedded blanks or tabs.
  217.  
  218.     <section> is a number or one of the following names:
  219.             code
  220.             data
  221.             none               (becomes section -1)
  222.             absolute        (becomes section -2)
  223.             transfer        (becomes section -3)
  224.  
  225.     <offset> is a numeric offset into the section.  
  226.  
  227.     The optional <class> (default is "data") is a number 
  228.     or one of the following class names:
  229.             code
  230.             data
  231.             tvector
  232.             tocentry
  233.             glue
  234.  
  235.     The line can also be a blank line or a comment line, 
  236.     where comment lines begin with a "#" or "*" character 
  237.     and extend to the end of the line.
  238.  
  239.  
  240.     For example, to add two symbols defining the start of the code and
  241.     data sections, the file could contain these lines:
  242.         *
  243.         # This file defines two exported symbols for the start of the 
  244.         # code and data sections
  245.         *
  246.         startOfCode code:0 code
  247.         startOfData data 0 data
  248.  
  249.  
  250. To rename imported/exported symbols
  251. -----------------------------------
  252.  
  253.     ModPEF <old> -o <new> -@renamesymbols <fragspec>=<filename>
  254.  
  255.     The file <filename> contains lines of pairs of symbols: <oldName> <newName>.
  256.     Each occurrence of an <oldName> as a symbol in an import library or export 
  257.     list in the specified fragment is replaced with <newName>.  The new file is 
  258.     written to <new>.
  259.  
  260.     Format of the lines in the -@renamesymbols file is 
  261.  
  262.             <oldName> <newName>
  263.  
  264.     The <...name> is anything without embedded blanks or tabs.
  265.  
  266.     The line can also be a blank line or a comment line, 
  267.     where comment lines begin with a "#" or "*" character 
  268.     and extend to the end of the line.
  269.  
  270.  
  271. To assign aliases to exported symbols
  272. -------------------------------------
  273.  
  274.     ModPEF <old> -o <new> -@alias <fragspec>=<filename>
  275.  
  276.     The file <filename> contains lines of pairs of symbols: <oldName> <newName>.
  277.     Each occurrence of an <oldName> as a symbol in an export list in the specified 
  278.     fragment is given the alias <newName>.  The new file is written to <new>.
  279.  
  280.     Format of the lines in the -@alias file is 
  281.  
  282.             <oldName> <newName>
  283.  
  284.     The <...name> is anything without embedded blanks or tabs.
  285.  
  286.     The line can also be a blank line or a comment line, 
  287.     where comment lines begin with a "#" or "*" character 
  288.     and extend to the end of the line.
  289.  
  290.  
  291.     For example, to add aliases for two symbols, the file could contain these lines:
  292.         *
  293.         # This file adds aliases for two symbols
  294.         *
  295.         MyPublic    MyPublic_3r
  296.         Version        Version_3r
  297.  
  298.  
  299. To delete exported symbols
  300. --------------------------
  301.  
  302.     ModPEF <old> -o <new> -@deleteexports <fragspec>=<filename>
  303.     ModPEF <old> -o <new> -deleteexports <fragspec>=<aName>,...
  304.  
  305.     The file <filename> contains symbols, one per line.  Each symbol so named 
  306.     is deleted from the export section of the fragment.  The new file is written 
  307.     to <new>.
  308.  
  309.     Format of the lines in the -@deleteexports file is 
  310.  
  311.             <exportedName>
  312.  
  313.     The <...name> is anything without embedded blanks or tabs.
  314.  
  315.     The line can also be a blank line or a comment line, 
  316.     where comment lines begin with a "#" or "*" character 
  317.     and extend to the end of the line.
  318.  
  319.  
  320. Decreasing runtime memory footprint
  321. -----------------------------------
  322.  
  323.     ModPEF <old> -o <new> -mergecode on | off
  324.  
  325.     -mergecode on will create overlapping fragments in the output file.  The
  326.     code sections of each container will be made physically adjacent.  This 
  327.     merging can improve paging behavior when fragments are loaded from the 
  328.     library.  When no merging is done, one code page from a container's code
  329.     section will contain non-code such as the pieces of the piData or loader
  330.     section.  That non-code is wasted once the fragment has been initialized.  
  331.     By overlapping fragments and making code sections physically adjacent, the 
  332.     non-code from one fragment's code section will be the code from another 
  333.     fragment's code section.  Although we cannot guarantee that the other code 
  334.     will be used and decrease overall memory footprint, we at least increase 
  335.     the probability of improving paging behavior.
  336.  
  337.  
  338. Controlling descriptions
  339. ------------------------
  340.  
  341.     ModPEF -describe on | off
  342.  
  343.     By default "on", ModPEF describes which resources are affected by the
  344.     -extract, -delete and -merge operations.
  345.  
  346.  
  347.  
  348. ==============
  349. The fine print
  350. ==============
  351.  
  352. 1.    Input files are never modified.  
  353.  
  354. 2.    Only one CFM-68K application is allowed per file.
  355.     Because of the 'RSEG'(0) and 'RSEG'(1) resources, only one 680x0 application 
  356.     can appear in a file.  Attempts to add more than one CFM-68K application will 
  357.     generate an error message.
  358.  
  359. 3.    The -mergecode option has no effect on CFM-68K applications.
  360.     Because the 680x0 code is stored in the resource fork, no merging of code is
  361.     possible.
  362.  
  363. 4.    Import library names and versions can go stale.
  364.     ModPEF does not touch the import libraries part of the loader section.  If a 
  365.     fragment has its version numbers modified, any references to it in the import 
  366.     libraries section of other fragments will not be changed.  You have been warned.
  367.  
  368. 5.    The -describe option defaults to "on".
  369.     Because a file can contain multiple versions of a fragment for different 
  370.     architectures and with different version numbers, the default behavior is to 
  371.     describe which fragments are being affected by ModPEF.  
  372.  
  373.